[preview] Update Safety Events

Asynchronously update eventState and/or context labels for one or more Safety Events. Returns 202 Accepted immediately. State changes propagate asynchronously; use GET /safety-events to confirm updated state. If any safetyEventIds are not found, the entire request fails with 404 before any mutations are executed. If both eventState and label fields are provided, the two mutations execute serially and are not transactional — a label mutation failure will not roll back a successful state change.

Rate limit: 5 requests/sec (learn more about rate limits here).

To use this endpoint, select Write Safety Events & Scores under the Safety & Cameras category when creating or editing an API token. Learn More.

Endpoints in this section are in Preview. These APIs are not functional and are instead for soliciting feedback from our API users on the intended design of this API. Additionally, it is not guaranteed that we will be releasing an endpoint included in this section to production. This means that developers should NOT rely on these APIs to build business critical applications

• Samsara may change the structure of a preview API’s interface without versioning or any notice to API users.

• When an endpoint becomes generally available, it will be announced in the API changelog.

Submit Feedback: Likes, dislikes, and API feature requests should be filed as feedback in our API feedback form. If you encountered an issue or noticed inaccuracies in the API documentation, please submit a case to our support team.

PATCH /preview/safety-events/batch

[preview] Update Safety Events

cURL

curl --request PATCH \
  --url https://api.samsara.com/preview/safety-events/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "safetyEventIds": [
    "bb2ff5ab-30ad-49ec-9d2d-55ec30bbf590",
    "bb2ff5ab-30ad-49ec-9d2d-55ec30bbf590",
    "bb2ff5ab-30ad-49ec-9d2d-55ec30bbf590"
  ],
  "contextLabelsToAdd": [
    "Snowing",
    "Wet Road",
    "Passengers",
    "Defensive"
  ],
  "contextLabelsToRemove": [
    "Congested",
    "Passenger Mobile Usage",
    "Passenger Sleeping",
    "Snowing"
  ],
  "eventState": "needsReview"
}
'

202

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "responses": [
    {
      "data": {
        "safetyEventId": "bb2ff5ab-30ad-49ec-9d2d-55ec30bbf590"
      },
      "status": 202
    }
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request body for updating Safety Events. At least one of eventState, contextLabelsToAdd, or contextLabelsToRemove must be provided. Maximum 200 IDs per request.

safetyEventIds · string[] · required

IDs of the Safety Events to update. Maximum 200.

The unique Samsara ID (uuid) of the safety event.

Example:

[
  "bb2ff5ab-30ad-49ec-9d2d-55ec30bbf590",
  "bb2ff5ab-30ad-49ec-9d2d-55ec30bbf590",
  "bb2ff5ab-30ad-49ec-9d2d-55ec30bbf590"
]

contextLabelsToAdd · enum<string>[]

Context labels to add to the Safety Events.

A context label to add. Valid values: Congested, Construction, Coupling/Uncoupling, Cyclist/Motorcyclist, Defensive, Fog, Improper Seat Belt, Light Traffic, Moderate Traffic, Moderately Drowsy, Mounted Phone, Night, Parking Lot, Passenger Mobile Usage, Passenger Sleeping, Passengers, Pedestrians, Raining, Sensitive Media, Slightly Drowsy, Snowing, Snowy Road, Speed Sign Verified, Very Drowsy, Wet Road, Wildlife

Available options: Congested, Construction, Coupling/Uncoupling, Cyclist/Motorcyclist, Defensive, Fog, Improper Seat Belt, Light Traffic, Moderate Traffic, Moderately Drowsy, Mounted Phone, Night, Parking Lot, Passenger Mobile Usage, Passenger Sleeping, Passengers, Pedestrians, Raining, Sensitive Media, Slightly Drowsy, Snowing, Snowy Road, Speed Sign Verified, Very Drowsy, Wet Road, Wildlife

Example:

[
  "Snowing",
  "Wet Road",
  "Passengers",
  "Defensive"
]

contextLabelsToRemove · enum<string>[]

Context labels to remove from the Safety Events.

A context label to remove. Valid values: Congested, Construction, Coupling/Uncoupling, Cyclist/Motorcyclist, Defensive, Fog, Improper Seat Belt, Light Traffic, Moderate Traffic, Moderately Drowsy, Mounted Phone, Night, Parking Lot, Passenger Mobile Usage, Passenger Sleeping, Passengers, Pedestrians, Raining, Sensitive Media, Slightly Drowsy, Snowing, Snowy Road, Speed Sign Verified, Very Drowsy, Wet Road, Wildlife

Available options: Congested, Construction, Coupling/Uncoupling, Cyclist/Motorcyclist, Defensive, Fog, Improper Seat Belt, Light Traffic, Moderate Traffic, Moderately Drowsy, Mounted Phone, Night, Parking Lot, Passenger Mobile Usage, Passenger Sleeping, Passengers, Pedestrians, Raining, Sensitive Media, Slightly Drowsy, Snowing, Snowy Road, Speed Sign Verified, Very Drowsy, Wet Road, Wildlife

Example:

[
  "Congested",
  "Passenger Mobile Usage",
  "Passenger Sleeping",
  "Snowing"
]

dismissalReason · object

Dismissal reason. Required when eventState is dismissed. Must not be provided for other states.

Show child attributes

eventState · enum<string>

The new state to apply to all specified Safety Events. Valid values: needsReview, reviewed, needsCoaching, coached, dismissed, needsRecognition, recognized

Available options: needsReview, reviewed, needsCoaching, coached, dismissed, needsRecognition, recognized

Example:

"needsReview"

Response

202

application/json

Accepted response.

requestId · string · required

Server-generated UUID for client-side correlation and logging. Not stored or queryable on the backend.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

responses · object[] · required

One entry per requested safetyEventId, in the same order as the request.

Show child attributes